If you are reading this, I'll assume that you know what Retro Native Forth is. If you don't, go back and read the Introduction to Retro Native Forth. Retro is a simple system, yet to gain its full benefits you'll need to recompile it for your system. This process isn't difficult, and I'll give plenty of examples, so be patient.

Before we start:
  1) If the precompiled versions are  working, and you don't need or want
     the latest new features, don't recompile it.
  2) If you're a kernel developer, or have problems, read on.
  3) Make sure you have the _latest_ version of NASM installed.

Ok, if you're reading on, here's the basic process: edit the build script. This is the main point if you're having problems. If you open it in an editor, it'll look something like this:

nasm retro.asm -oretro -Dplatform.native -Drune
nasm loaders/floppy/raw.asm -oimages/rawfloppy
nasm retro.asm -oretro -Dplatform.native -Dvesa -Drune
nasm loaders/dos/dos.asm -oimages/retro.com
nasm loaders/floppy/fat12.asm -oimages/fat12
nasm -felf retro.asm -Dplatform.linux -llistings/linux.lst && ld retro.o -s -oimages/rf
nasm -felf retro.asm -Dplatform.beos -llistings/beos.lst && ld retro.o -s -oimages/BeRetro


Each line compiles a specific part or port of Retro. By default it recompiles everything, so one quick hack to speed up compile time is to cut out what you don't want. For instance, if you don't use the raw floppy image, you can cut out the first two lines leaving this:

nasm retro.asm -oretro -Dplatform.native -Dvesa -Drune
nasm loaders/dos/dos.asm -oimages/retro.com
nasm loaders/floppy/fat12.asm -oimages/fat12
nasm -felf retro.asm -Dplatform.linux -llistings/linux.lst && ld retro.o -s -oimages/rf
nasm -felf retro.asm -Dplatform.beos -llistings/beos.lst && ld retro.o -s -oimages/BeRetro

Here's what's what in the default build script:
1)  nasm retro.asm -oretro -Dplatform.native -Drune
2)  nasm loaders/floppy/raw.asm -oimages/rawfloppy
3)  nasm retro.asm -oretro -Dplatform.native -Dvesa -Drune
4)  nasm loaders/dos/dos.asm -oimages/retro.com
5)  nasm loaders/floppy/fat12.asm -oimages/fat12
6)  nasm -felf retro.asm -Dplatform.linux -llistings/linux.lst && ld retro.o -s -oimages/rf
7)  nasm -felf retro.asm -Dplatform.beos -llistings/beos.lst && ld retro.o -s -oimages/BeRetro

Lines 1 & 2: The raw floppy, 320x200 graphics, support for Rune
Lines 3, 4 & 5: The FAT12 images, 640x480 graphics, support for Rune
Line 6: Text mode, Linux version
Line 7: Text mode, BeOS version


Some people have trouble running Retro with their video cards, especially on older computers. In many cases this can be fixed by turning off VESA support. Just cut off the -Dvesa line

nasm retro.asm -oretro -Dplatform.native -Drune


Each of the -D endings is a compile time option. To change settings, you can just add or remove these entries.

-Dplatform.XXX
   Tells what platform to compile for (e.g. native is the OS, linux for running under Linux, etc)
-Dvesa
   Enables VESA mode 0x101 (640x480x256 color graphics) instead of Mode 0x13 (320x200x256 color graphics). This is set by default, but causes problems on older machines. Only supported with -Dplatform.native
-Drune
   Enables the Rune Interface, a prototype of the eventual semi-graphical interface Retro will use. It is best used with -Dvesa, though it can be used in Mode 0x13. It also requires -Dplatform.native


After changing this file, save it, then recompile. The new binary images will be placed in the retro6/source/images/ directory. To boot from the new image, copy it to a floppy (use dd or rawrite for a raw floppy, or copy retro.com onto the FAT12 one; you need to use the retro6/source/images/fat12 boot sector) Read "Making a Retro 6 Boot Disk" if you have trouble making a bootable disk.

That's it for most changes if you're not a kernel developer. If you install any modified packages (such as BlueBar or an updated version of Rune), you'll probably just need to run the build.bat file again.


Kernel developers (and those who want total control of the customization process), read on. Otherwise you can stop now.


To get the most out of the Retro 6 Build system, you'll need to be running Linux (or maybe a BSD varient). (Windows users should download CYGWIN to match the needed functionality)

Download any updates you want, or add your own extensions into the proper directories. Switch to a console, and goto the retro6/source directory. I keep it in my home directory, so for me the lines are:

# cd ~/retro6/source

Don't type the #. Ok, you now need to rebuild the include files. You can do this by hand, but Linux (or Cygwin) makes it a lot easier.

# . mkincludes

Then just rebuild. If the code is valid, it should work properly.

# sh build.bat

And that's the whole process. For most tasks you don't need to touch any source files other than the ones in retro6/source/boot/* which is all Forth code anyway. I hope this was a help, and have fun hacking Retro!